﻿namespace Mp3Observer.Interfaces
{
    #region usings

    using System;
    using Mp3Observer.Model.Sound; 

    #endregion

    /// <summary>
    /// Contract for the MP3 Music Player.
    /// </summary>
    public interface IMusicPlayer
    {
        /// <summary>
        /// Occurs when the Player State changed.
        /// This Event is called on the Setter of the <see cref="State"/> property.
        /// </summary>
        event EventHandler<PlayerStateEventArgs> PlayerStateChanged;

        /// <summary>
        /// Gets or sets the state.
        /// </summary>
        /// <value>The state.</value>
        /// <remarks>
        /// State is initialized with None;
        /// If <see cref="Stop"/>  called, state is <seealso cref="PlayerState.Stopped"/>
        /// If file is player and playing is stopped because of end of file, state is set to <seealso cref="PlayerState.NativeStopped"/>
        /// </remarks>
        /// <example>
        /// Example if using the NativeStopped state in the Player ViewModel:
        /// <code>
        /// <![CDATA[
        ///   private void Player_PlayerStateChanged(object sender, PlayerStateEventArgs e)
        ///     {
        ///         this.OnPropertyChanged("IsPlaying");
        ///         if (e.PlayerState == PlayerState.NativeStopped)
        ///             if (this.IsNextPlayListItemAvailable)
        ///                 this.PlayNextFile();
        ///     }
        /// ]]>
        /// </code>
        /// Example on using the state on the CanExecute:
        /// <code>
        /// <![CDATA[
        ///     private bool CanStopFile()
        ///     {
        ///         return this.player.State == PlayerState.Playing || this.player.State == PlayerState.Paused;
        ///     }
        /// ]]>
        /// </code>
        /// </example>
        PlayerState State { get; set; }

        /// <summary>
        /// Gets or sets the file position.
        /// </summary>
        /// <value>The file position.</value>
        uint FilePosition { get; set; }

        /// <summary>
        /// Gets or sets the volume. (from 0 to 1)
        /// </summary>
        /// <value>The volume.</value>
        float Volume { get; set; }

        /// <summary>
        /// Gets or sets the frequency.
        /// </summary>
        /// <value>The frequency.</value>
        float Frequency { get; set; }

        /// <summary>
        /// Gets or sets the pan. (from 0 to -1)
        /// </summary>
        /// <value>The pan left/right.</value>
        float Pan { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether this <see cref="IMusicPlayer"/> is mute.
        /// </summary>
        /// <value><c>true</c> if mute; otherwise, <c>false</c>.</value>
        bool Mute { get; set; }

        /// <summary>
        /// Gets or sets the pitch. (between 0 and 10)
        /// </summary>
        /// <value>The pitch.</value>
        float Pitch { get; set; }

        /// <summary>
        /// Gets the length of the file.
        /// </summary>
        /// <value>The length of the file.</value>
        uint FileLength { get; }

        /// <summary>
        /// Gets the current timeposition and maximum timeposition.
        /// </summary>
        /// <value>The position and time.</value>
        /// <example>
        /// 00:00:00/00:00:00
        /// </example>
        string PositionAndTime { get; }

        /// <summary>
        /// Gets the equalizer.
        /// </summary>
        /// <value>The equalizer.</value>
        IEqualizer Equalizer { get; }

        /// <summary>
        /// Shutdown this player instance. (release unmanaged resources)
        /// </summary>
        void Shutdown();

        /// <summary>
        /// Plays the specified file name.
        /// </summary>
        /// <param name="fileName">Name of the file.</param>
        void Play(string fileName);

        /// <summary>
        /// Pauses or resumes the player.
        /// </summary>
        void Pause();

        /// <summary>
        /// Stops the player.
        /// </summary>
        void Stop();

        /// <summary>
        /// Gets the oscilliscope float data.
        /// Float values for each channel.
        /// </summary>
        /// <returns>the fload array with data</returns>
        float[][] GetOscilliscope();

        /// <summary>
        /// Gets the spectrum float data.
        /// Float values for each channel.
        /// </summary>
        /// <returns>the fload array with data</returns>
        float[][] GetSpectrum();
    }
}
